home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
IRIX Base Documentation 1998 November
/
IRIX 6.5.2 Base Documentation November 1998.img
/
usr
/
share
/
catman
/
p_man
/
cat3
/
SLGetQueue.z
/
SLGetQueue
Wrap
Text File
|
1998-10-30
|
10KB
|
199 lines
SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333))))
NNNNAAAAMMMMEEEE
SLGetQueue - reports the printer queue contents
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
####iiiinnnncccclllluuuuddddeeee <<<<ssssppppoooooooollll....hhhh>>>>
iiiinnnntttt SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((ccccoooonnnnsssstttt SSSSLLLLPPPPrrrriiiinnnntttteeeerrrrSSSSttttrrrruuuucccctttt ****pppprrrriiiinnnntttteeeerrrr____iiiinnnnffffoooo,,,,
iiiinnnntttt qqqquuuueeeeuuuueeee____ttttyyyyppppeeee,,,,
SSSSLLLLQQQQuuuueeeeuuuueeeeSSSSttttrrrruuuucccctttt ****qqqquuuueeeeuuuueeeepppp[[[[]]]],,,,
iiiinnnntttt ****nnnnuuuummmm____qqqquuuueeeeuuuueeeepppp))));;;;
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
_S_L_G_e_t_Q_u_e_u_e returns a list of the jobs on the queue for the specified
printer. The function uses the current default spooling system.
The _p_r_i_n_t_e_r__i_n_f_o parameter specifies the printer whose queue is to be
reported. Note that this parameter is a pointer to an _S_L_P_r_i_n_t_e_r_S_t_r_u_c_t
structure and not a printer name. This is because _S_L_G_e_t_Q_u_e_u_e requires
information available in the structure to properly locate and read the
printer queue. A NNNNUUUULLLLLLLL _p_r_i_n_t_e_r__i_n_f_o parameter is illegal and will return
an error. Values for this parameter can be obtained directly from the
printer list returned by the _S_L_G_e_t_P_r_i_n_t_e_r_L_i_s_t(_3) function.
_q_u_e_u_e__t_y_p_e specifies the type of queue to obtain. The value of this
parameter is used only for networked printers under the System V spooler.
Under the System V Release 3 spooling system there are two queues for a
networked printer, the queue on the local machine and the queue on the
remote machine. _q_u_e_u_e__t_y_p_e specifies which of these two queues should be
read and provides the capability to merge the two queues into one list.
The possible values for _q_u_e_u_e__t_y_p_e are:
SSSSLLLL____QQQQUUUUEEEEUUUUEEEE____LLLLOOOOCCCCAAAALLLL Obtain the network printer queue on the local
machine.
SSSSLLLL____QQQQUUUUEEEEUUUUEEEE____RRRREEEEMMMMOOOOTTTTEEEE Obtain the network printer queue on the remote host
machine.
SSSSLLLL____QQQQUUUUEEEEUUUUEEEE____MMMMEEEERRRRGGGGEEEEDDDD Merge the local and remote printer queues into one
list. If a print job appears in both the local and
remote printer queues, only the local job will be
listed.
_q_u_e_u_e_p is set by the function to point to a list of _S_L_Q_u_e_u_e_S_t_r_u_c_t
structures. These structures contain detailed information about each job
in the printer queue. _n_u_m__q_u_e_u_e_p is set to the number of jobs in the
queue list.
The _S_L_Q_u_e_u_e_S_t_r_u_c_t is defined as:
typedef struct _slQueueStruct {
char *job_id; /* Job ID */
char *username; /* Job owner's user name */
PPPPaaaaggggeeee 1111
SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333))))
char *title; /* Print job title, or name */
/* of first file in request */
unsigned int size; /* Size of the job in bytes */
unsigned int is_local: 1; /* 1 == job is in the local */
/* queue (Sys V only) */
unsigned int _padding: 31; /* Unused - for alignment */
time_t time_stamp; /* Submittal time */
} SLQueueStruct;
RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
0 is returned if execution was successful. -1 is returned and _S_L_e_r_r_n_o is
set if an execution error has occurred.
EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS
_S_L_G_e_t_Q_u_e_u_e will fail under the following circumstances.
SL_ERR_FIND_SPOOLER An error occurred while attempting to determine
the available printer spooling systems.
SL_ERR_NO_SPOOLERS There are no printer spooling systems available.
SL_ERR_SPOOLER_ERROR A printer spooling system error has occurred.
SL_ERR_BAD_PRINTER_STRUCT
An invalid printer structure has been specified.
SL_ERR_REMOTE An error has occurred while attempting a remote
shell execution (rsh). This error could be
caused by transitory network problems. The
function call should be retried.
WWWWAAAARRRRNNNNIIIINNNNGGGG
A pointer to _q_u_e_u_e_p obtained by a previous call to _S_L_G_e_t_Q_u_e_u_e will be
invalid after subsequent calls to the function. The contents of the queue
list _q_u_e_u_e_p must be copied to be preserved. Note that the character
string fields of the structure must be duplicated in any copy operation
since these pointers also become invalid.
NNNNOOOOTTTTEEEESSSS
All mention of "fields" refers to the fields of the _S_L_Q_u_e_u_e_S_t_r_u_c_t
structure.
1. Under the BSD spooling system the _t_i_m_e__s_t_a_m_p field will be set to
the 0.
2. The _q_u_e_u_e__t_y_p_e parameter is only used by the System V spooling
system when a networked printer is specified. In all other cases the
value of this parameter is ignored.
PPPPaaaaggggeeee 2222
SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333))))
3. The _t_i_m_e__s_t_a_m_p field contains the value returned by the time(2)
function. Refer to the time(2) and ctime(3) man pages for
information about the time value and how it may be converted to a
time string.
4. Under System V spooling _S_L_G_e_t_Q_u_e_u_e must perform network command
execution to obtain queue information for a remote printer. If a
connection to the remote machine cannot be established _S_L_G_e_t_Q_u_e_u_e
will return an error indication and set _S_L_e_r_r_n_o to SSSSLLLL____EEEERRRRRRRR____RRRREEEEMMMMOOOOTTTTEEEE.
Upon receiving this error, an application should retry the call a
number of times to ensure that the failure is not due to a
transitory network problem.
5. Under System V spooling _S_L_G_e_t_Q_u_e_u_e must perform network command
execution to obtain queue information for a remote printer. Remote
command execution is attempted as the user 'lp'. Normally, the lp
account will not have a passwd and access is freely granted. If an
installation protects the lp account with a password and uses the
rhosts mechanism, _S_L_G_e_t_Q_u_e_u_e will fail to get permission to access
the remote queue. An example of how an application might handle
this situation is to run as a setuid lp program and bracket its
calls to _S_L_G_e_t_Q_e_u_e_u_e with the _s_e_t_r_e_u_i_d(_2) and _s_e_t_r_e_g_i_d(_2) functions.
For example, assume that the following code is executed by a program
that has uid=joe and euid=lp.
/* Swap uid with euid and gid with egid.
Thus uid=lp and euid=joe
*/
setreuid(geteuid(), getuid());
setregid(getegid(), getgid());
/* Get the remote queue as lp */
SLGetQueue(prptr, queue_type, &queue, &numjobs);
/* Swap everything back. Thus uid=joe and euid=lp */
setreuid(geteuid(), getuid());
setregid(getegid(), getgid());
6. The _t_i_t_l_e field will be NNNNUUUULLLLLLLL if _l_i_b_s_p_o_o_l was unable to determine the
title of a print job.
SSSSEEEEEEEE AAAALLLLSSSSOOOO
SLGetPrinterList(3), SLSubmitJob(3), SLPerror(3), libspool(3) time(2),
ctime(3), setreuid(2), setregid(2)
PPPPaaaaggggeeee 3333